Debugger

Taken from the FCEUXDSP1.07 documentation.

Introduction

The debugger is a powerful tool that reads, displays, and manipulates assembly language instructions in a game.

Debugger Features

-When you hold the mouse over the left pane in the debugger, you can now see the ROM file address of the data loaded there. -Right-click in that pane, it will bring up the Hex Editor at that address so you can immediately begin editing.

-Left-clicking in that pane brings up the inline assembler.

-"Break on bad opcode" feature; this can help you figure out where your game is crashing. Middle-clicking on a byte will bring up the

Game Genie Encoder at that address, so you can easily make Game Genie codes.

-Debugging data like breakpoints or bookmarks are automatically saved and restored when games are closed / opened.

-Ability to give breakpoints a brief description/name.

-All debugging information for addresses < $8000 into the name list file romname.nes.ram.nl.

-Added a feature to NL files to support arrays.

-Range options for freezing / unfreezing addresses

-Dump RAM to file option

-Dump PPU memory to file option

-Automatically generated .deb debug files created if the debugger is used.

Using Debugger

Symbolic Debugging

The most important feature (at least for me) that was introduced in FCEUXD SP is symbolic debugging. With this new feature it's possible to rename addresses in the disassembly window (like $C022) to easily understandable names (like AddHealthpoints). It's also possible to add comments to lines in the disassembly window.

To be able to use this feature it's necessary to create so called name list files (*.nl) which contain all names and comments you wish to display in the disassembly window. These files are plain ASCII files of the following format (example follows):

$C000#NewName1#Comment1

$C002##Comment2

$C004#NewName2#

$C006#NewName3#MultilineComment-Part1

\MultilineComment-Part2

\MultilineComment-Part3

$C008/10#NewName4#

Every line contains two # characters which separate the three parts of one line: The first part (starting with a $ character) is the address to be renamed. Optionally you can add a "/number" part which marks the offsets as a beginning of an array of the given size (the size must be specified in hex form). The second (optional) part is the new name of that address. Whenever the line of that address is shown in the disassembly window an extra line saying "Name: NewName" is shown above it. Instructions referencing this address, for example JSR $C000 are also changed to JSR NewName1 (in that example). The third (optional) part is the comment that's also added above the disassembly line the comment refers to. It works exactly like the additional name line, only the prefix of that line is different. Comment lines start with "Comment: " rather than with "Name: ". Multi-lines comments are possible. Lines starting with a \ character are just appended to the comment of the preceding line. Multi-line comments are also shown in multiple lines in the disassembly window.

Let's get back to the example.

The first line contains all three parts. Using this name list file all references to the address

$C000 are replaced with NewName1 and whenever line $C000 is shown in the disassembly window an

additional comment is also visible right above the actual disassembled line.

The second line defines only a comment while the third line defines only a name. Following that

there's a multi-line comment definition for address $C006.

The last line defines an array called NewName4 of size $10 (= 16) bytes starting at offset $C008.

Now you know the format of the nl files but you do not yet know the naming convention for the

file names. Due to the bank-swapping nature of the NES it's getting a little bit difficult here.

Each bank needs it's own nl file. The naming convention goes like this: Take the name of the ROM

file and just add ".X.nl" to it where the X is the hexadecimal representation of the number of the

ROM bank. Suppose you have the ROM file "Faxanadu (U).nes" and you want to create a nl file for

ROM bank 15. As 15 is 0x0F in hex the name of the nl file would be "Faxanadu (U).nes.F.nl". All

nl files go into the same directory as the ROM file itself.

You can enable and disable symbolic debugging by clicking the checkbox "Symbolic Debugging" in

the debugger window. To forcibly reload the nl files of the currently active ROM file press the

button with the text "Reload Symbols".

Arrays

The array feature is an easy way to group names and comments for sequential offsets.

$C000/5#NewName1#Comment1

is equivalent to

$C000#NewName1#Comment1

Inline Assembler

The debugger an Inline Assembler designed by Parasyte. To activate it, left-click in the left pane of the debugger, beside the assembly display. To use it, type in some code and press Enter to add it to the patch list. If you make a mistake, press "Undo". Once the patch is set up the way you want it, press "Apply". Be aware that this cannot be undone unless you reload the ROM. Parasyte implemented this feature before I had the Hex Editor working, otherwise I would have implemented a way to undo it from there. Press "Save" to write to the ROM file on disk; note that this will also save any changes you may have done in the Hex Editor.

2008

This help file has been generated by the freeware version of HelpNDoc